refactor(logging): rename llama_stack logger categories by Elbehery · Pull Request #3065 · ogx-ai/ogx

Elbehery · 2025-08-07T17:08:35Z

What does this PR do?

This PR renames categories of llama_stack loggers.

This PR aligns logging categories as per the package name, as well as reviews from initial #2868. This is a follow up to #3061.

Replaces #2868
Part of #2865

cc @leseb @rhuss

rhuss · 2025-08-11T07:24:21Z

How have you checked the file base for missing alignment of the log category with the package name? Can you please show me your vibe coding context & prompt?

When I use

LLS uses statements like 
`get_logger(name=__name__, category="core")` to specify a category. 
This category aligns with the package name 
(e.g., here it's the directory `llama_stack/core/server/auth_providers.py` that uses the
top-level dir as category name. Show me all places where
this alignment doesn't match.

I find quite a few more spots (actually 27 instead of 5). Can you check again, please? Also, can you please specify which "rule" you used to map the package name (file path)? I'm assuming you always use the first path component, but it sometimes seems that the category is randomly picked from* some* path component of the Python file.

It should be consistent and unambiguous, so that there is a clear rule also for the future, which category name to pick.

File	Expected	Actual	Notes
llama_stack/core/utils/config_resolution.py	core	config_resolution
llama_stack/core/server/server.py	core	server	2 occurrences
llama_stack/core/server/quota.py	core	quota
llama_stack/core/server/auth_providers.py	core	auth
llama_stack/core/server/auth.py	core	auth
llama_stack/providers/utils/telemetry/tracing.py	providers	core
llama_stack/providers/remote/inference/ollama/ollama.py	providers	inference
llama_stack/providers/inline/telemetry/meta_reference/console_span_processor.py	providers	telemetry
llama_stack/providers/utils/inference/litellm_openai_mixin.py	providers	inference
llama_stack/providers/inline/agents/meta_reference/agent_instance.py	providers	agents
llama_stack/providers/utils/tools/mcp.py	providers	tools
llama_stack/providers/utils/sqlstore/authorized_sqlstore.py	providers	authorized_sqlstore
llama_stack/providers/remote/tool_runtime/model_context_protocol/model_context_protocol.py	providers	tools
llama_stack/providers/remote/inference/together/together.py	providers	inference
llama_stack/providers/remote/inference/fireworks/fireworks.py	providers	inference
llama_stack/providers/utils/inference/model_registry.py	providers	core
llama_stack/providers/remote/inference/vllm/vllm.py	providers	inference
llama_stack/providers/utils/inference/openai_mixin.py	providers	core
llama_stack/providers/inline/inference/meta_reference/inference.py	providers	inference
llama_stack/providers/utils/sqlstore/sqlalchemy_sqlstore.py	providers	sqlstore
llama_stack/providers/inline/agents/meta_reference/openai_responses.py	providers	openai_responses
llama_stack/providers/utils/inference/prompt_adapter.py	providers	inference
llama_stack/providers/utils/scheduler.py	providers	scheduler
llama_stack/providers/inline/post_training/torchtune/common/checkpointer.py	providers	uncategorized	get_logger("DEBUG") uses default category
llama_stack/cli/stack/run.py	cli	server
llama_stack/models/llama/tokenizer_utils.py	models	tokenizer_utils
llama_stack/models/llama/llama3/tool_utils.py	models	inference

File	Expected	Actual	Notes
`llama_stack/core/utils/config_resolution.py`	core	config_resolution
`llama_stack/core/server/server.py`	core	server	2 occurrences
`llama_stack/core/server/quota.py`	core	quota
`llama_stack/core/server/auth_providers.py`	core	auth
`llama_stack/core/server/auth.py`	core	auth
`llama_stack/providers/utils/telemetry/tracing.py`	providers	core
`llama_stack/providers/remote/inference/ollama/ollama.py`	providers	inference
`llama_stack/providers/inline/telemetry/meta_reference/console_span_processor.py`	providers	telemetry
`llama_stack/providers/utils/inference/litellm_openai_mixin.py`	providers	inference
`llama_stack/providers/inline/agents/meta_reference/agent_instance.py`	providers	agents
`llama_stack/providers/utils/tools/mcp.py`	providers	tools
`llama_stack/providers/utils/sqlstore/authorized_sqlstore.py`	providers	authorized_sqlstore
`llama_stack/providers/remote/tool_runtime/model_context_protocol/model_context_protocol.py`	providers	tools
`llama_stack/providers/remote/inference/together/together.py`	providers	inference
`llama_stack/providers/remote/inference/fireworks/fireworks.py`	providers	inference
`llama_stack/providers/utils/inference/model_registry.py`	providers	core
`llama_stack/providers/remote/inference/vllm/vllm.py`	providers	inference
`llama_stack/providers/utils/inference/openai_mixin.py`	providers	core
`llama_stack/providers/inline/inference/meta_reference/inference.py`	providers	inference
`llama_stack/providers/utils/sqlstore/sqlalchemy_sqlstore.py`	providers	sqlstore
`llama_stack/providers/inline/agents/meta_reference/openai_responses.py`	providers	openai_responses
`llama_stack/providers/utils/inference/prompt_adapter.py`	providers	inference
`llama_stack/providers/utils/scheduler.py`	providers	scheduler
`llama_stack/providers/inline/post_training/torchtune/common/checkpointer.py`	providers	uncategorized	`get_logger("DEBUG")` uses default category
`llama_stack/cli/stack/run.py`	cli	server
`llama_stack/models/llama/tokenizer_utils.py`	models	tokenizer_utils
`llama_stack/models/llama/llama3/tool_utils.py`	models	inference

27 mismatches found.

rhuss · 2025-08-11T07:25:31Z

 from llama_stack.log import get_logger

-logger = get_logger(name=__name__, category="auth")
+logger = get_logger(name=__name__, category="core")


what is the rule to extract the category ? First path element ("core") or shouldn't it be last path element ("server") ?

so I initially use the first path element, but over some reviews on the original PR, I have changed them accordingly :)

rhuss · 2025-08-11T07:26:17Z

 from llama_stack.providers.utils.responses.responses_store import ResponsesStore

-logger = get_logger(name=__name__, category="openai_responses")
+logger = get_logger(name=__name__, category="agents")


Which "agents" (randomly from within the package name) and not "providers" (first path element in the package) ?

rhuss · 2025-08-11T07:29:58Z

It's also ok to introduce a more complex rule-set like:

Top-level package dir in general
For providers: The first directory below providers/{inline,remote}, but with inline:: and remote:: prefixed, respectively.
....

Please propose such a rule-set. It shouldn't be too involved, though. Try to keep it less than 5 rules.
Again it should not be too complicated, but we then can add this rule-set to the CLAUDE.md or .cursor/ prompts, so that in the future the right logging category gets automatically picked up.

Elbehery · 2025-08-11T09:54:59Z

How have you checked the file base for missing alignment of the log category with the package name? Can you please show me your vibe coding context & prompt?

When I use
LLS uses statements like 
`get_logger(name=__name__, category="core")` to specify a category. 
This category aligns with the package name 
(e.g., here it's the directory `llama_stack/core/server/auth_providers.py` that uses the
top-level dir as category name. Show me all places where
this alignment doesn't match.
I find quite a few more spots (actually 27 instead of 5). Can you check again, please? Also, can you please specify which "rule" you used to map the package name (file path)? I'm assuming you always use the first path component, but it sometimes seems that the category is randomly picked from* some* path component of the Python file.

It should be consistent and unambiguous, so that there is a clear rule also for the future, which category name to pick.
File Expected Actual Notes
llama_stack/core/utils/config_resolution.py core config_resolution
llama_stack/core/server/server.py core server 2 occurrences
llama_stack/core/server/quota.py core quota
llama_stack/core/server/auth_providers.py core auth
llama_stack/core/server/auth.py core auth
llama_stack/providers/utils/telemetry/tracing.py providers core
llama_stack/providers/remote/inference/ollama/ollama.py providers inference
llama_stack/providers/inline/telemetry/meta_reference/console_span_processor.py providers telemetry
llama_stack/providers/utils/inference/litellm_openai_mixin.py providers inference
llama_stack/providers/inline/agents/meta_reference/agent_instance.py providers agents
llama_stack/providers/utils/tools/mcp.py providers tools
llama_stack/providers/utils/sqlstore/authorized_sqlstore.py providers authorized_sqlstore
llama_stack/providers/remote/tool_runtime/model_context_protocol/model_context_protocol.py providers tools
llama_stack/providers/remote/inference/together/together.py providers inference
llama_stack/providers/remote/inference/fireworks/fireworks.py providers inference
llama_stack/providers/utils/inference/model_registry.py providers core
llama_stack/providers/remote/inference/vllm/vllm.py providers inference
llama_stack/providers/utils/inference/openai_mixin.py providers core
llama_stack/providers/inline/inference/meta_reference/inference.py providers inference
llama_stack/providers/utils/sqlstore/sqlalchemy_sqlstore.py providers sqlstore
llama_stack/providers/inline/agents/meta_reference/openai_responses.py providers openai_responses
llama_stack/providers/utils/inference/prompt_adapter.py providers inference
llama_stack/providers/utils/scheduler.py providers scheduler
llama_stack/providers/inline/post_training/torchtune/common/checkpointer.py providers uncategorized get_logger("DEBUG") uses default category
llama_stack/cli/stack/run.py cli server
llama_stack/models/llama/tokenizer_utils.py models tokenizer_utils
llama_stack/models/llama/llama3/tool_utils.py models inference
File Expected Actual Notes
llama_stack/core/utils/config_resolution.py core config_resolution
llama_stack/core/server/server.py core server 2 occurrences
llama_stack/core/server/quota.py core quota
llama_stack/core/server/auth_providers.py core auth
llama_stack/core/server/auth.py core auth
llama_stack/providers/utils/telemetry/tracing.py providers core
llama_stack/providers/remote/inference/ollama/ollama.py providers inference
llama_stack/providers/inline/telemetry/meta_reference/console_span_processor.py providers telemetry
llama_stack/providers/utils/inference/litellm_openai_mixin.py providers inference
llama_stack/providers/inline/agents/meta_reference/agent_instance.py providers agents
llama_stack/providers/utils/tools/mcp.py providers tools
llama_stack/providers/utils/sqlstore/authorized_sqlstore.py providers authorized_sqlstore
llama_stack/providers/remote/tool_runtime/model_context_protocol/model_context_protocol.py providers tools
llama_stack/providers/remote/inference/together/together.py providers inference
llama_stack/providers/remote/inference/fireworks/fireworks.py providers inference
llama_stack/providers/utils/inference/model_registry.py providers core
llama_stack/providers/remote/inference/vllm/vllm.py providers inference
llama_stack/providers/utils/inference/openai_mixin.py providers core
llama_stack/providers/inline/inference/meta_reference/inference.py providers inference
llama_stack/providers/utils/sqlstore/sqlalchemy_sqlstore.py providers sqlstore
llama_stack/providers/inline/agents/meta_reference/openai_responses.py providers openai_responses
llama_stack/providers/utils/inference/prompt_adapter.py providers inference
llama_stack/providers/utils/scheduler.py providers scheduler
llama_stack/providers/inline/post_training/torchtune/common/checkpointer.py providers uncategorized get_logger("DEBUG") uses default category
llama_stack/cli/stack/run.py cli server
llama_stack/models/llama/tokenizer_utils.py models tokenizer_utils
llama_stack/models/llama/llama3/tool_utils.py models inference
* 27 mismatches found.

thanks for your review

so from the table, I conclude that the correct category, is the outer package name, (e.g. for llama_stack/providers/utils/inference/prompt_adapter.py, the category is provider)

Elbehery · 2025-08-11T10:08:03Z

It's also ok to introduce a more complex rule-set like:
* Top-level package dir in general

* For providers: The first directory below `providers/{inline,remote}`, but with `inline::` and `remote::` prefixed, respectively.

* ....
Please propose such a rule-set. It shouldn't be too involved, though. Try to keep it less than 5 rules. Again it should not be too complicated, but we then can add this rule-set to the CLAUDE.md or .cursor/ prompts, so that in the future the right logging category gets automatically picked up.

thanks for your guidance

please find my proposal below

Generally, use the Top-level package name.
For core, use the last package name. Please find examples below to clarify.
- For llama_stack/core/utils/config_resolution.py use utils.
- For llama_stack/core/server/server.py use server.
- For llama_stack/providers/remote/inference/ollama/ollama.py use remote::inference::ollama.
- For llama_stack/models/llama/llama3/tool_utils.py use llama3

ptal 👍🏽

rhuss · 2025-08-11T14:51:50Z

thanks for the proposal

For core, use the last package name if relevant (e.g. server or auth), otherwise, fall to the top-level package name (i.e. core). Please find examples below to clarify

"if relevant" should never be part of any rule, as there is a lot of leeway in interpretation about what is actually "relevant".

You could say:

For all sub-packages of core/server, use "server". Otherwise, use "core" for anything else. Although I would be ok to also use the last component for everything below "core".

However, I would be equally acceptable to handpick a selection and not rely solely on the file path. For that, one should define the full list of categories. Perhaps it's better not to connect the package name, as I don't see any regularity right now that could be leveraged to fully determine the log category from the package / directory name.

Elbehery · 2025-08-11T15:13:08Z

"if relevant" should never be part of any rule, as there is a lot of leeway in interpretation about what is actually "relevant".

+1, I will remove it above, it should be clear to avoid confusion in the future 👍🏽

Perhaps it's better not to connect the package name, as I don't see any regularity right now that could be leveraged to fully determine the log category from the package / directory name.

+1, therefore I sometimes used the package name and other use the top-level package name.

I would appreciate input from others in order to have consensus over the categories names used now, and in the future

cc @leseb @ashwinb @mattf @nathan-weinberg @skamenan7 @derekhiggins @bbrowning @cdoern @ehhuang

Elbehery · 2025-08-14T07:02:13Z

As Per @ashwinb review in #3065 (comment)

Logging Category	Description	Apply Under Directories
`core::server`	Base server lifecycle, FastAPI app, routes, quotas	`llama_stack/core/server/` (excluding `auth*.py`)
`core::auth`	Authentication/authorization, request identity, access control	`llama_stack/core/access_control/`
`core::<component>`	Core orchestration: routers, routing tables, stores, registry	`llama_stack/core/routers/`, `llama_stack/core/routing_tables/`, `llama_stack/core/store/`
`cli`	CLI entrypoints, commands, installers	`llama_stack/cli/`
`distribution`	Packaged stack distributions, templates, CI test stacks	`llama_stack/distributions/`
`testing`	Test utilities and recorders	`llama_stack/testing/`
`ui`	Python UI backend and helpers	`llama_stack/core/ui/`
`providers::utils`	Shared provider utilities (schedulers, telemetry, SQL stores, tooling)	`llama_stack/providers/utils/`
`<type>::<provider>`	Inline providers (run in-process); type reflects API area (agents, inference, scoring, telemetry, etc.) and provider is the provider ID	`llama_stack/providers/inline/<type>/<provider>/`
`<type>::<provider>`	Remote providers (call out-of-process/cloud); same type/provider semantics	`llama_stack/providers/remote/<type>/<provider>/`
`model::llama`	Llama 3 model family-specific code	`llama_stack/models/llama/llama3/`
`model::llama`	Llama 3.1 model family-specific code	`llama_stack/models/llama/llama3_1/`
`model::llama`	Llama 3.2 model family-specific code	`llama_stack/models/llama/llama3_2/`
`model::llama`	Llama 3.3 model family-specific code	`llama_stack/models/llama/llama3_3/`
`model::llama`	Llama 4 model family-specific code	`llama_stack/models/llama/llama4/`

This is the final proposal, i will apply it to #3061 now

Elbehery · 2025-08-14T07:15:38Z

@rhuss updated according to the table in #3065 (comment)

All changes here impacts loggers which is already in the code base, before merging #3061

I propose to merge this first, so that I can rebase #3061 before updating the categories.

thanks

Elbehery · 2025-08-21T11:36:25Z

cc @mattf this is a follow up to #3061

ashwinb

I am good with this PR mostly I have a couple of comments inline mostly the addition of a file which feels like a mistake.

ashwinb · 2025-08-21T23:07:28Z

 from llama_stack.providers.utils.kvstore.config import KVStoreConfig, SqliteKVStoreConfig

-logger = get_logger(__name__, category="core")
+logger = get_logger(__name__, category="core::store")


just name this core::registry

fixed 👍🏽

ashwinb · 2025-08-21T23:08:13Z

 )

-logger = get_logger(name=__name__, category="responses")
+logger = get_logger(name=__name__, category="agents::meta_reference")


I think this should stay responses really, maybe call this openai::responses. this is why we cannot take these dictums too formally sometimes.

fixed 👍🏽

ashwinb · 2025-08-21T23:08:59Z

@@ -0,0 +1,1154 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.


why is this file added? is that a bad rebase?

yes, the commit is older than removing this file

thanks for catching this 👍🏽

removed 👍🏽

This PR renames logging categores of llama_stack logger across the codebase according to #3065 (comment). Signed-off-by: Mustafa Elbehery <melbeher@redhat.com>

@leseb

# What does this PR do?  This PR renames categories of llama_stack loggers. This PR aligns logging categories as per the package name, as well as reviews from initial ogx-ai#2868. This is a follow up to ogx-ai#3061.   Replaces ogx-ai#2868 Part of ogx-ai#2865 cc @leseb @rhuss Signed-off-by: Mustafa Elbehery <melbeher@redhat.com>

Elbehery requested review from ashwinb, bbrowning, ehhuang, hardikjshah, leseb, mattf, raghotham, reluctantfuturist, slekkala1, terrytangyuan and yanxi0830 as code owners August 7, 2025 17:08

meta-cla Bot added the CLA Signed This label is managed by the Meta Open Source bot. label Aug 7, 2025

Elbehery mentioned this pull request Aug 7, 2025

chore: replace use llama_stack logger #3060

Closed

Elbehery force-pushed the 20250807_rename_logger_categories branch 2 times, most recently from 50b5ffe to 91cd285 Compare August 8, 2025 06:33

Elbehery closed this Aug 8, 2025

Elbehery deleted the 20250807_rename_logger_categories branch August 8, 2025 09:34

Elbehery restored the 20250807_rename_logger_categories branch August 8, 2025 09:35

Elbehery reopened this Aug 8, 2025

Elbehery force-pushed the 20250807_rename_logger_categories branch from 91cd285 to 96fbb8e Compare August 8, 2025 09:43

Elbehery changed the title ~~chore: rename log categories~~ refactor(logging): rename llama_stack logger categories Aug 8, 2025

rhuss reviewed Aug 11, 2025

View reviewed changes

Elbehery mentioned this pull request Aug 11, 2025

chore(pre-commit): add pre-commit hook to enforce llama_stack logger usage #3061

Merged

Elbehery force-pushed the 20250807_rename_logger_categories branch 2 times, most recently from 2257036 to e0cbe5d Compare August 14, 2025 07:13

Elbehery force-pushed the 20250807_rename_logger_categories branch 12 times, most recently from f991345 to 1bad897 Compare August 21, 2025 11:36

Elbehery force-pushed the 20250807_rename_logger_categories branch 2 times, most recently from 7515c9c to c97dc1c Compare August 21, 2025 23:04

ashwinb suggested changes Aug 21, 2025

View reviewed changes

Elbehery force-pushed the 20250807_rename_logger_categories branch 3 times, most recently from 7a98003 to 23ef375 Compare August 21, 2025 23:22

refactor(logging): rename llama_stack logger categories

430ea87

This PR renames logging categores of llama_stack logger across the codebase according to #3065 (comment). Signed-off-by: Mustafa Elbehery <melbeher@redhat.com>

Elbehery force-pushed the 20250807_rename_logger_categories branch from 23ef375 to 430ea87 Compare August 21, 2025 23:38

ashwinb approved these changes Aug 22, 2025

View reviewed changes

ashwinb merged commit c3b2b06 into ogx-ai:main Aug 22, 2025
23 checks passed

Elbehery deleted the 20250807_rename_logger_categories branch August 22, 2025 07:32

Elbehery mentioned this pull request Sep 22, 2025

Add pre-commit hook to check the logger #2865

Closed

		@@ -0,0 +1,1154 @@
		# Copyright (c) Meta Platforms, Inc. and affiliates.

Uh oh!

Conversation

Elbehery commented Aug 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do?

Uh oh!

rhuss commented Aug 11, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rhuss commented Aug 11, 2025

Uh oh!

Elbehery commented Aug 11, 2025

Uh oh!

Elbehery commented Aug 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rhuss commented Aug 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Elbehery commented Aug 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Elbehery commented Aug 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Elbehery commented Aug 14, 2025

Uh oh!

Elbehery commented Aug 21, 2025

Uh oh!

ashwinb left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Elbehery commented Aug 7, 2025 •

edited

Loading

Elbehery commented Aug 11, 2025 •

edited

Loading

rhuss commented Aug 11, 2025 •

edited

Loading

Elbehery commented Aug 11, 2025 •

edited

Loading

Elbehery commented Aug 14, 2025 •

edited

Loading